/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import java.util.Set;

import org.springframework.beans.BeansException;
import org.springframework.beans.TypeConverter;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.NoSuchBeanDefinitionException;
import org.springframework.beans.factory.NoUniqueBeanDefinitionException;
import org.springframework.lang.Nullable;

/**
 * Extension of the {@link org.springframework.beans.factory.BeanFactory}
 * interface to be implemented by bean factories that are capable of
 * autowiring, provided that they want to expose this functionality for
 * existing bean instances.
 *
 * BeanFactory 接口的拓展，通过具备自动装配能力的bean 工厂实现，提供了他们想暴露给存在的 bean 实例的功能
 *
 * <p>This subinterface of BeanFactory is not meant to be used in normal
 * application code: stick to {@link org.springframework.beans.factory.BeanFactory}
 * or {@link org.springframework.beans.factory.ListableBeanFactory} for
 * typical use cases.
 *
 * 本 BeanFactory 子接口 不是为了使用在正常的应用代码中；
 * 典型的使用案例遵循 BeanFactory 或者 ListableBeanFactory 接口
 *
 * <p>Integration code for other frameworks can leverage this interface to
 * wire and populate existing bean instances that Spring does not control
 * the lifecycle of. This is particularly useful for WebWork Actions and
 * Tapestry Page objects, for example.
 *
 * -- （错误翻译：）其他框架可以借用本接口进行装配集成（integration） 的代码，并且推进存在的其他 Spring 没有管理生命周期的 bean 实例
 * 其他框架的集成代码||可以利用本接口进行装配并且填充 不受 Spring 生命周期管理的已经存在的 bean 实例；
 * 比如说，这对于 WebWork 框架中的 Actions 和 Tapestry Page 对象而言尤其重要
 * 【其他框架的集成】
 *
 * <p>Note that this interface is not implemented by
 * {@link org.springframework.context.ApplicationContext} facades,
 * as it is hardly ever used by application code. That said, it is available
 * from an application context too, accessible through ApplicationContext's
 * {@link org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()}
 * method.
 *
 * 注意：这个接口不是通过 ApplicationContext 门面实现的，因为它几乎不在应用代码中被使用。
 * 尽管如此，本接口也是可以从 应用上下文中获得的，通过 getAutowireCapableBeanFactory 方法。
 * 【没有被 ApplicationContext 继承】
 *
 * <p>You may also implement the {@link org.springframework.beans.factory.BeanFactoryAware}
 * interface, which exposes the internal BeanFactory even when running in an
 * ApplicationContext, to get access to an AutowireCapableBeanFactory:
 * simply cast the passed-in BeanFactory to AutowireCapableBeanFactory.
 *
 * 你也可以实现 BeanFactoryAware 接口，该接口可以暴露内部的 BeanFactory 甚至在运行一个应用上下文的时候，
 * 要访问一个 AutowireCapableBeanFactory ,只需要将传入的 BeanFactory 强制转换（cast） 为 AutowireCapableBeanFactory
 * 【常用的应该也是使用 BeanFactoryAware 接口获得应用上下文】
 *
 * （：扩展了自动装配的功能，根据类定义 BeanDefinition 装配 Bean、执行后置处理器等）
 * （个人感觉这个接口非常重要，因为 Spring 主要的特性之一 依赖注入的重要步骤就是 自动装配！Autowired
 * 行动上，就是将 bean populate 到其他的 bean 完成他们的 协作/依赖关系
 * ）
 *
 * @author Juergen Hoeller
 * @since 04.12.2003
 * @see org.springframework.beans.factory.BeanFactoryAware
 * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory
 * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()
 */
public interface AutowireCapableBeanFactory extends BeanFactory {

	/**
	 * Constant that indicates no externally defined autowiring. Note that
	 * BeanFactoryAware etc and annotation-driven injection will still be applied.
	 *
	 * no autowire
	 * 指示没有外部定义的自动装配。
	 * 注意：BeanFactory 等，以及基于注解启动的注入，仍然会被应用。
	 *
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_NO = 0;

	/**
	 * Constant that indicates autowiring bean properties by name
	 * (applying to all bean property setters).
	 *
	 * 指示 通过名称自动装配 bean 属性。
	 * （通过 setters 的方式应用所有的 bean）
	 *
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_BY_NAME = 1;

	/**
	 * Constant that indicates autowiring bean properties by type
	 * (applying to all bean property setters).
	 *
	 * 指示 通过类型自动装配 bean 的属性
	 * （通过 setters 的方式应用所有的 bean）
	 *
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_BY_TYPE = 2;

	/**
	 * Constant that indicates autowiring the greediest constructor that
	 * can be satisfied (involves resolving the appropriate constructor).
	 *
	 * 指示 自动装配 适配的贪婪（参数尽可能多而且又合适） 的构造器
	 * （调用 解析合适的构造器）
	 *
	 * @see #createBean
	 * @see #autowire
	 */
	int AUTOWIRE_CONSTRUCTOR = 3;

	/**
	 * Constant that indicates determining an appropriate autowire strategy
	 * through introspection of the bean class.
	 * @see #createBean
	 * @see #autowire
	 * @deprecated as of Spring 3.0: If you are using mixed autowiring strategies,
	 * prefer annotation-based autowiring for clearer demarcation of autowiring needs.
	 */
	@Deprecated
	int AUTOWIRE_AUTODETECT = 4;


	//-------------------------------------------------------------------------
	// Typical methods for creating and populating external bean instances
	// 经典的 创建和填充 外部 bean 实例
	//-------------------------------------------------------------------------

	/**
	 * Fully create a new bean instance of the given class.
	 * <p>Performs full initialization of the bean, including all applicable
	 * {@link BeanPostProcessor BeanPostProcessors}.
	 * <p>Note: This is intended for creating a fresh instance, populating annotated
	 * fields and methods as well as applying all standard bean initialization callbacks.
	 * It does <i>not</> imply traditional by-name or by-type autowiring of properties;
	 * use {@link #createBean(Class, int, boolean)} for those purposes.
	 *
	 * 完全的创建一个 bean 实例。
	 * 表现为该 bean 的完全初始化，包括所有适用的 BeanPostProcessors
	 * 注意：这个是为了创建一个新的实例，填充被注解的字段和方法，并且提供所有标准的bean 初始化的回调。
	 * 它并不意味着（imply）传统的 通过名字或者通过类型进行属性的自动装配；
	 * 适用 {@link #createBean(Class, int, boolean)} 方法进行上述的控制。
	 *
	 * @param beanClass the class of the bean to create
	 * @return the new bean instance
	 * @throws BeansException if instantiation or wiring failed
	 */
	<T> T createBean(Class<T> beanClass) throws BeansException;

	/**
	 * Populate the given bean instance through applying after-instantiation callbacks
	 * and bean property post-processing (e.g. for annotation-driven injection).
	 * <p>Note: This is essentially intended for (re-)populating annotated fields and
	 * methods, either for new instances or for deserialized instances. It does
	 * <i>not</i> imply traditional by-name or by-type autowiring of properties;
	 * use {@link #autowireBeanProperties} for those purposes.
	 *
	 * 通过 应用 after-instantiation 的回调方法
	 * 和 bean 的属性后置处理（比如：对于注解驱动的注入）
	 * 来填充 给定的 bean 实例；
	 * 【after-instantiation + post-processing】
	 * 注意：这本质上是为了 重新填充带注解的属性和方法，无论是新实例还是反序列化的实例。
	 * （？？？？为什么需要重新填充呢？？？？）
	 * 这并不意味着传统的 通过名字或者通过类型的 属性自动装配；
	 * 使用 {@link #autowireBeanProperties} 进行传统的按名字或类型装配。
	 *
	 * @param existingBean the existing bean instance
	 * @throws BeansException if wiring failed
	 */
	void autowireBean(Object existingBean) throws BeansException;

	/**
	 * Configure the given raw bean: autowiring bean properties, applying
	 * bean property values, applying factory callbacks such as {@code setBeanName}
	 * and {@code setBeanFactory}, and also applying all bean post processors
	 * (including ones which might wrap the given raw bean).
	 * <p>This is effectively a superset of what {@link #initializeBean} provides,
	 * fully applying the configuration specified by the corresponding bean definition.
	 * <b>Note: This method requires a bean definition for the given name!</b>
	 *
	 * 配置给定的原生 bean :
	 * 	自动装配 bean 属性；
	 * 	应用 bean 的属性值；
	 * 	应用 工厂的回调方法 比如：{@code setBeanName} 和 {@code setBeanFactory}
	 * 	应用所有的 bean 后置处理器，包括那些可能装饰了原生 bean 的后置处理器。
	 * 这 实际上（effectively）是 基于 {@link #initializeBean} 方法提供的超集，
	 * 完全地应用相应的 bean 定义 指定的（specified） 进行配置。
	 * 注意：本方法要求给定的名称必须存在对应的 bean 定义！
	 * 【装配工具由 initializeBean 方法提供 】
	 *
	 * @param existingBean the existing bean instance
	 * @param beanName the name of the bean, to be passed to it if necessary
	 * (a bean definition of that name has to be available)
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
	 * if there is no bean definition with the given name
	 * @throws BeansException if the initialization failed
	 * @see #initializeBean
	 */
	Object configureBean(Object existingBean, String beanName) throws BeansException;


	//-------------------------------------------------------------------------
	// Specialized methods for fine-grained control over the bean lifecycle
	// bean 生命周期细粒度控制的专门的方法
	//-------------------------------------------------------------------------

	/**
	 * Fully create a new bean instance of the given class with the specified
	 * autowire strategy. All constants defined in this interface are supported here.
	 * <p>Performs full initialization of the bean, including all applicable
	 * {@link BeanPostProcessor BeanPostProcessors}. This is effectively a superset
	 * of what {@link #autowire} provides, adding {@link #initializeBean} behavior.
	 *
	 * 完全地创建一个新的给定类型的 bean 实例，使用具体的自动装配策略。
	 * 这个接口的所有的常量定义，在这个方法都支持！
	 * 表现为 Bean 的完全初始化，包括所有的适用的 BeanPostProcessor。
	 * 这个实际上是 {@link #autowire} 方法提供的超集，附加了 {@link #initializeBean} 方法的行为。
	 *
	 * @param beanClass the class of the bean to create
	 * @param autowireMode by name or type, using the constants in this interface
	 * @param dependencyCheck whether to perform a dependency check for objects
	 * (not applicable to autowiring a constructor, thus ignored there)
	 * @return the new bean instance
	 * @throws BeansException if instantiation or wiring failed
	 * @see #AUTOWIRE_NO
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 * @see #AUTOWIRE_CONSTRUCTOR
	 */
	Object createBean(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;

	/**
	 * Instantiate a new bean instance of the given class with the specified autowire
	 * strategy. All constants defined in this interface are supported here.
	 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply
	 * before-instantiation callbacks (e.g. for annotation-driven injection).
	 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
	 * callbacks or perform any further initialization of the bean. This interface
	 * offers distinct, fine-grained operations for those purposes, for example
	 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
	 * callbacks are applied, if applicable to the construction of the instance.
	 *
	 * 使用具体的自动装配策略 实例化一个给定类的新的 bean 实例。
	 * 这个接口的所有的常量定义，在这个方法都支持！
	 * 可以使用 {@code AUTOWIRE_NO} 参数来调用本方法，只是为了应用 before-instantiation 回调（比如：基于注解注入）
	 *
	 * 不会应用标准的 BeanPostProcessor 回调或者表现更进一步的 bean 初始化。
	 * 为了那些目的，这个接口提供了不重复的，细粒度的操作，比如 {@link #initializeBean}
	 * 然而，如果 {@link InstantiationAwareBeanPostProcessor} 实例化感知后置处理器 适用该实例的构造方法，
	 * 会被回调。
	 * 【不会使用 BeanPostProcessor 除了 InstantiationAwareBeanPostProcessor】
	 *
	 * @param beanClass the class of the bean to instantiate
	 * @param autowireMode by name or type, using the constants in this interface
	 * @param dependencyCheck whether to perform a dependency check for object
	 * references in the bean instance (not applicable to autowiring a constructor,
	 * thus ignored there)
	 * @return the new bean instance
	 * @throws BeansException if instantiation or wiring failed
	 * @see #AUTOWIRE_NO
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 * @see #AUTOWIRE_CONSTRUCTOR
	 * @see #AUTOWIRE_AUTODETECT
	 * @see #initializeBean
	 * @see #applyBeanPostProcessorsBeforeInitialization
	 * @see #applyBeanPostProcessorsAfterInitialization
	 */
	Object autowire(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;

	/**
	 * Autowire the bean properties of the given bean instance by name or type.
	 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply
	 * after-instantiation callbacks (e.g. for annotation-driven injection).
	 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
	 * callbacks or perform any further initialization of the bean. This interface
	 * offers distinct, fine-grained operations for those purposes, for example
	 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
	 * callbacks are applied, if applicable to the configuration of the instance.
	 *
	 * 通过名称或者类型 对于给定的实例的 bean 属性进行自动装配。
	 * （其他基本同上）
	 *
	 * @param existingBean the existing bean instance
	 * @param autowireMode by name or type, using the constants in this interface
	 * @param dependencyCheck whether to perform a dependency check for object
	 * references in the bean instance
	 * @throws BeansException if wiring failed
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 * @see #AUTOWIRE_NO
	 */
	void autowireBeanProperties(Object existingBean, int autowireMode, boolean dependencyCheck)
			throws BeansException;

	/**
	 * Apply the property values of the bean definition with the given name to
	 * the given bean instance. The bean definition can either define a fully
	 * self-contained bean, reusing its property values, or just property values
	 * meant to be used for existing bean instances.
	 * <p>This method does <i>not</i> autowire bean properties; it just applies
	 * explicitly defined property values. Use the {@link #autowireBeanProperties}
	 * method to autowire an existing bean instance.
	 * <b>Note: This method requires a bean definition for the given name!</b>
	 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
	 * callbacks or perform any further initialization of the bean. This interface
	 * offers distinct, fine-grained operations for those purposes, for example
	 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
	 * callbacks are applied, if applicable to the configuration of the instance.
	 *
	 * 把 根据给定的名称获得的 bean 定义 设置给传入的 bean 实例；
	 * bean 定义可以定义一个
	 * 	完全 自包含（self-contained）的 bean，重复使用它的属性值；
	 * 	或者 只定义用于现有 bean 实例的属性值。
	 * 这个方法不会自动装配 bean 属性；
	 * 它只会提供显示的定义属性值。
	 * 使用 {@link #autowireBeanProperties} 方法去自动装配一个存在的 bean 实例。
	 * 注意：本方法要求给定的名称必须存在对应的 bean 定义！
	 *
	 * 不会应用标准的 BeanPostProcessor 回调或者表现更进一步的 bean 初始化。
	 * 为了那些目的，这个接口提供了不重复的，细粒度的操作，比如 {@link #initializeBean}
	 * 然而，如果 {@link InstantiationAwareBeanPostProcessor} 实例化感知后置处理器 适用该实例的构造方法，
	 * 会被回调。
	 *
	 * @param existingBean the existing bean instance
	 * @param beanName the name of the bean definition in the bean factory
	 * (a bean definition of that name has to be available)
	 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
	 * if there is no bean definition with the given name
	 * @throws BeansException if applying the property values failed
	 * @see #autowireBeanProperties
	 */
	void applyBeanPropertyValues(Object existingBean, String beanName) throws BeansException;

	/**
	 * Initialize the given raw bean, applying factory callbacks
	 * such as {@code setBeanName} and {@code setBeanFactory},
	 * also applying all bean post processors (including ones which
	 * might wrap the given raw bean).
	 * <p>Note that no bean definition of the given name has to exist
	 * in the bean factory. The passed-in bean name will simply be used
	 * for callbacks but not checked against the registered bean definitions.
	 *
	 * 应用工厂的回调方法，比如 {@code setBeanName} and {@code setBeanFactory}
	 * 应用所有的 bean 后置处理器（包括那些装饰给的原生 bean 的后置处理器）
	 * 初始化给定的原生 bean。
	 * 注意：给定名称的 bean 定义不必存在在 bean 工厂中。
	 * 传入的 beanName 只是用于回调，但是没有根据注册的 bean 定义检查。
	 *
	 * @param existingBean the existing bean instance
	 * @param beanName the name of the bean, to be passed to it if necessary
	 * (only passed to {@link BeanPostProcessor BeanPostProcessors})
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException if the initialization failed
	 */
	Object initializeBean(Object existingBean, String beanName) throws BeansException;

	/**
	 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
	 * instance, invoking their {@code postProcessBeforeInitialization} methods.
	 * The returned bean instance may be a wrapper around the original.
	 *
	 * 给 给定的存在的 bean 实例应用 Bean 后置处理器，调用 {@code postProcessBeforeInitialization} 方法。
	 * 返回的 bean 实例可能是个原始 bean 实例的环绕装饰 bean 实例。
	 *
	 * @param existingBean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException if any post-processing failed
	 * @see BeanPostProcessor#postProcessBeforeInitialization
	 */
	Object applyBeanPostProcessorsBeforeInitialization(Object existingBean, String beanName)
			throws BeansException;

	/**
	 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
	 * instance, invoking their {@code postProcessAfterInitialization} methods.
	 * The returned bean instance may be a wrapper around the original.
	 *
	 * 给 给定的存在的 bean 实例应用 Bean 后置处理器，调用 {@code postProcessAfterInitialization} 方法。
	 * 	 * 返回的 bean 实例可能是个原始 bean 实例的环绕装饰 bean 实例。
	 *
	 * @param existingBean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException if any post-processing failed
	 * @see BeanPostProcessor#postProcessAfterInitialization
	 */
	Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName)
			throws BeansException;

	/**
	 * Destroy the given bean instance (typically coming from {@link #createBean}),
	 * applying the {@link org.springframework.beans.factory.DisposableBean} contract as well as
	 * registered {@link DestructionAwareBeanPostProcessor DestructionAwareBeanPostProcessors}.
	 * <p>Any exception that arises during destruction should be caught
	 * and logged instead of propagated to the caller of this method.
	 *
	 * 应用 DisposableBean 协议，以及注册的 DestructionAwareBeanPostProcessors
	 * 摧毁一个给定的 bean 实例（典型的来自 createBean 方法创造出来），
	 * 在破坏（destruction）过程中产生的任何异常应该被捕获，并且被记录，
	 * 而不是传播（propagate）到本方法的调用方！
	 *
	 * @param existingBean the bean instance to destroy
	 */
	void destroyBean(Object existingBean);


	//-------------------------------------------------------------------------
	// Delegate methods for resolving injection points
	// 解析注入点 的委托方法
	//-------------------------------------------------------------------------

	/**
	 * Resolve the bean instance that uniquely matches the given object type, if any,
	 * including its bean name.
	 * <p>This is effectively a variant of {@link #getBean(Class)} which preserves the
	 * bean name of the matching instance.
	 *
	 * 解析
	 * 	唯一匹配给定的对象的类型的bean 实例（如果有的话），
	 * 	包括他的 bean 名称
	 * 这个实际上是 {@link #getBean(Class)} 的变体，保留了匹配实例的 bean 名称。
	 *
	 * @param requiredType type the bean must match; can be an interface or superclass.
	 * {@code null} is disallowed.
	 * @return the bean name plus bean instance
	 * @throws NoSuchBeanDefinitionException if no matching bean was found
	 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found
	 * @throws BeansException if the bean could not be created
	 * @since 4.3.3
	 * @see #getBean(Class)
	 */
	<T> NamedBeanHolder<T> resolveNamedBean(Class<T> requiredType) throws BeansException;

	/**
	 * Resolve the specified dependency against the beans defined in this factory.
	 *
	 * 解析本工厂中定义的 beans 的具体的依赖关系。
	 *
	 * @param descriptor the descriptor for the dependency (field/method/constructor)
	 * @param requestingBeanName the name of the bean which declares the given dependency
	 * @return the resolved object, or {@code null} if none found
	 * @throws NoSuchBeanDefinitionException if no matching bean was found
	 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found
	 * @throws BeansException if dependency resolution failed for any other reason
	 * @since 2.5
	 * @see #resolveDependency(DependencyDescriptor, String, Set, TypeConverter)
	 */
	@Nullable
	Object resolveDependency(DependencyDescriptor descriptor, @Nullable String requestingBeanName) throws BeansException;

	/**
	 * Resolve the specified dependency against the beans defined in this factory.
	 *
	 * （同上）
	 * TODO: 这个模板方法相当重要。具体的实现看 DefaultListableBeanFactory
	 *
	 * @param descriptor the descriptor for the dependency (field/method/constructor)
	 * @param requestingBeanName the name of the bean which declares the given dependency
	 * @param autowiredBeanNames a Set that all names of autowired beans (used for
	 * resolving the given dependency) are supposed to be added to
	 * @param typeConverter the TypeConverter to use for populating arrays and collections
	 * @return the resolved object, or {@code null} if none found
	 * @throws NoSuchBeanDefinitionException if no matching bean was found
	 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found
	 * @throws BeansException if dependency resolution failed for any other reason
	 * @since 2.5
	 * @see DependencyDescriptor
	 */
	@Nullable
	Object resolveDependency(DependencyDescriptor descriptor, @Nullable String requestingBeanName,
			@Nullable Set<String> autowiredBeanNames, @Nullable TypeConverter typeConverter) throws BeansException;

}
